to TTTTccccllll____CCCCrrrreeeeaaaatttteeeeCCCCoooommmmmmmmaaaannnndddd. |
The command must not have|
been deleted.
DDDDEEEESSSSCCCCRRRRIIIIPPPPTTTTIIIIOOOONNNN
TTTTccccllll____CCCCrrrreeeeaaaatttteeeeCCCCoooommmmmmmmaaaannnndddd defines a new command in _i_n_t_e_r_p and associates it with
procedure _p_r_o_c such that whenever _c_m_d_N_a_m_e is invoked as a Tcl command
(via a call to TTTTccccllll____EEEEvvvvaaaallll) the Tcl interpreter will call _p_r_o_c to process
the command. If there is already a command _c_m_d_N_a_m_e associated with the
interpreter, it is deleted. TTTTccccllll____CCCCrrrreeeeaaaatttteeeeCCCCoooommmmmmmmaaaannnndddd returns a token that may |
be used to refer to the command in subsequent calls to |
TTTTccccllll____GGGGeeeettttCCCCoooommmmmmmmaaaannnnddddNNNNaaaammmmeeee. _P_r_o_c should have arguments and result that match the
type TTTTccccllll____CCCCmmmmddddPPPPrrrroooocccc:
typedef int Tcl_CmdProc(
ClientData _c_l_i_e_n_t_D_a_t_a,
Tcl_Interp *_i_n_t_e_r_p,
int _a_r_g_c,
char *_a_r_g_v[]);
When _p_r_o_c is invoked the _c_l_i_e_n_t_D_a_t_a and _i_n_t_e_r_p parameters will be copies
of the _c_l_i_e_n_t_D_a_t_a and _i_n_t_e_r_p arguments given to TTTTccccllll____CCCCrrrreeeeaaaatttteeeeCCCCoooommmmmmmmaaaannnndddd.
Typically, _c_l_i_e_n_t_D_a_t_a points to an application-specific data structure
that describes what to do when the command procedure is invoked. _A_r_g_c
and _a_r_g_v describe the arguments to the command, _a_r_g_c giving the number of
arguments (including the command name) and _a_r_g_v giving the values of the
arguments as strings. The _a_r_g_v array will contain _a_r_g_c+1 values; the
first _a_r_g_c values point to the argument strings, and the last value is
NULL.
_P_r_o_c must return an integer code that is either TTTTCCCCLLLL____OOOOKKKK, TTTTCCCCLLLL____EEEERRRRRRRROOOORRRR,
TTTTCCCCLLLL____RRRREEEETTTTUUUURRRRNNNN, TTTTCCCCLLLL____BBBBRRRREEEEAAAAKKKK, or TTTTCCCCLLLL____CCCCOOOONNNNTTTTIIIINNNNUUUUEEEE. See the Tcl overview man page
for details on what these codes mean. Most normal commands will only
return TTTTCCCCLLLL____OOOOKKKK or TTTTCCCCLLLL____EEEERRRRRRRROOOORRRR. In addition, _p_r_o_c must set _i_n_t_e_r_p->_r_e_s_u_l_t to
point to a string value; in the case of a TTTTCCCCLLLL____OOOOKKKK return code this gives
the result of the command, and in the case of TTTTCCCCLLLL____EEEERRRRRRRROOOORRRR it gives an error
message. The TTTTccccllll____SSSSeeeettttRRRReeeessssuuuulllltttt procedure provides an easy interface for
setting the return value; for complete details on how the _i_n_t_e_r_p->_r_e_s_u_l_t
field is managed, see the TTTTccccllll____IIIInnnntttteeeerrrrpppp man page. Before invoking a command
procedure, TTTTccccllll____EEEEvvvvaaaallll sets _i_n_t_e_r_p->_r_e_s_u_l_t to point to an empty string, so
simple commands can return an empty result by doing nothing at all.
The contents of the _a_r_g_v array belong to Tcl and are not guaranteed to |
persist once _p_r_o_c returns: _p_r_o_c should not modify them, nor should it |
set _i_n_t_e_r_p->_r_e_s_u_l_t to point anywhere within the _a_r_g_v values. Call |
TTTTccccllll____SSSSeeeettttRRRReeeessssuuuulllltttt with status TTTTCCCCLLLL____VVVVOOOOLLLLAAAATTTTIIIILLLLEEEE if you want to return something |
from the _a_r_g_v array.
_D_e_l_e_t_e_P_r_o_c will be invoked when (if) _c_m_d_N_a_m_e is deleted. This can occur
through a call to TTTTccccllll____DDDDeeeelllleeeetttteeeeCCCCoooommmmmmmmaaaannnndddd or TTTTccccllll____DDDDeeeelllleeeetttteeeeIIIInnnntttteeeerrrrpppp, or by replacing
_c_m_d_N_a_m_e in another call to TTTTccccllll____CCCCrrrreeeeaaaatttteeeeCCCCoooommmmmmmmaaaannnndddd. _D_e_l_e_t_e_P_r_o_c is invoked
